/*
 * @(#)Owner.java	1.10 01/12/12
 *
 * Sun Microsystems, Inc.版权所有版权所有。SUN专有/保密。使用受许可条款的约束。
 */

package java.security.acl;

import java.security.Principal;

/**
 * 管理ACL (Access Control Lists)所有者或ACL配置。
 * (注意，<code> java.security.acl </code>包中的Acl接口扩展了这个Owner接口。)
 * 应该将初始所有者Principal指定为实现此接口的类的构造函数的参数。
 *   
 * @see Acl
 *
 */
public interface Owner {

    /**
     * 添加一个所有者。只有所有者可以修改ACL的内容。调用方主体必须是ACL的所有者才能调用此方法。
     * 也就是说，只有一个所有者可以添加另一个所有者。在构建ACL时配置初始所有者。
     * 
     * @param caller the principal invoking this method. It must be an owner 
     * of the ACL.
     * 
     * @param owner the owner that should be added to the list of owners.
     * 
     * @return true if successful, false if owner is already an owner.
     * @exception NotOwnerException if the caller principal is not an owner 
     * of the ACL.
     */
    public boolean addOwner(Principal caller, Principal owner)
      throws NotOwnerException;

    /** 
     * 删除所有者。如果这是ACL中的最后一个所有者，则引发异常。<p>
     * 
     * 调用方主体必须是ACL的所有者才能调用此方法。
     * 
     * @param caller the principal invoking this method. It must be an owner 
     * of the ACL.
     * 
     * @param owner the owner to be removed from the list of owners.
     * 
     * @return true if the owner is removed, false if the owner is not part 
     * of the list of owners.
     * 
     * @exception NotOwnerException if the caller principal is not an owner 
     * of the ACL.
     * 
     * @exception LastOwnerException if there is only one owner left, so that
     * deleteOwner would leave the ACL owner-less.
     */
    public boolean deleteOwner(Principal caller, Principal owner)
      throws NotOwnerException, LastOwnerException;

    /**
     * Returns true if the given principal is an owner of the ACL.
     * 
     * @param owner the principal to be checked to determine whether or not 
     * it is an owner.
     * 
     * @return true if the passed principal is in the list of owners, false 
     * if not.
     */
    public boolean isOwner(Principal owner);

}
